<!doctype html>

<html>
<head>
  <link rel="shortcut icon" href="static/images/favicon.ico" type="image/x-icon">
  <title>component.js (Closure Library API Documentation - JavaScript)</title>
  <link rel="stylesheet" href="static/css/base.css">
  <link rel="stylesheet" href="static/css/doc.css">
  <link rel="stylesheet" href="static/css/sidetree.css">
  <link rel="stylesheet" href="static/css/prettify.css">

  <script>
     var _staticFilePath = "static/";
  </script>

  <script src="static/js/doc.js">
  </script>

  <meta charset="utf8">
</head>

<body onload="prettyPrint()">

<div id="header">
  <div class="g-section g-tpl-50-50 g-split">
    <div class="g-unit g-first">
      <a id="logo" href="index.html">Closure Library API Documentation</a>
    </div>

    <div class="g-unit">
      <div class="g-c">
        <strong>Go to class or file:</strong>
        <input type="text" id="ac">
      </div>
    </div>
  </div>
</div>

<div class="clear"></div>

<h2><a href="closure_goog_ui_component.js.html">component.js</a></h2>

<pre class="prettyprint lang-js">
<a name="line1"></a>// Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
<a name="line2"></a>// you may not use this file except in compliance with the License.
<a name="line3"></a>// You may obtain a copy of the License at
<a name="line4"></a>//
<a name="line5"></a>//     http://www.apache.org/licenses/LICENSE-2.0
<a name="line6"></a>//
<a name="line7"></a>// Unless required by applicable law or agreed to in writing, software
<a name="line8"></a>// distributed under the License is distributed on an &quot;AS IS&quot; BASIS,
<a name="line9"></a>// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
<a name="line10"></a>// See the License for the specific language governing permissions and
<a name="line11"></a>// limitations under the License.
<a name="line12"></a>
<a name="line13"></a>// Copyright 2007 Google Inc. All Rights Reserved.
<a name="line14"></a>
<a name="line15"></a>/**
<a name="line16"></a> * @fileoverview Abstract class for all UI components. This defines the standard
<a name="line17"></a> * design pattern that all UI components should follow.
<a name="line18"></a> *
<a name="line19"></a> */
<a name="line20"></a>
<a name="line21"></a>goog.provide(&#39;goog.ui.Component&#39;);
<a name="line22"></a>goog.provide(&#39;goog.ui.Component.Error&#39;);
<a name="line23"></a>goog.provide(&#39;goog.ui.Component.EventType&#39;);
<a name="line24"></a>goog.provide(&#39;goog.ui.Component.State&#39;);
<a name="line25"></a>
<a name="line26"></a>goog.require(&#39;goog.array&#39;);
<a name="line27"></a>goog.require(&#39;goog.dom&#39;);
<a name="line28"></a>goog.require(&#39;goog.dom.DomHelper&#39;);
<a name="line29"></a>goog.require(&#39;goog.events&#39;);
<a name="line30"></a>goog.require(&#39;goog.events.Event&#39;);
<a name="line31"></a>goog.require(&#39;goog.events.EventHandler&#39;);
<a name="line32"></a>goog.require(&#39;goog.events.EventTarget&#39;);
<a name="line33"></a>goog.require(&#39;goog.object&#39;);
<a name="line34"></a>goog.require(&#39;goog.style&#39;);
<a name="line35"></a>goog.require(&#39;goog.ui.IdGenerator&#39;);
<a name="line36"></a>
<a name="line37"></a>
<a name="line38"></a>/**
<a name="line39"></a> * Default implementation of UI component.
<a name="line40"></a> *
<a name="line41"></a> * @param {goog.dom.DomHelper} opt_domHelper Optional DOM helper.
<a name="line42"></a> * @constructor
<a name="line43"></a> * @extends {goog.events.EventTarget}
<a name="line44"></a> */
<a name="line45"></a>goog.ui.Component = function(opt_domHelper) {
<a name="line46"></a>  goog.events.EventTarget.call(this);
<a name="line47"></a>  this.dom_ = opt_domHelper || goog.dom.getDomHelper();
<a name="line48"></a>
<a name="line49"></a>  // Set the defalt right to left value.
<a name="line50"></a>  this.rightToLeft_ = goog.ui.Component.defaultRightToLeft_;
<a name="line51"></a>};
<a name="line52"></a>goog.inherits(goog.ui.Component, goog.events.EventTarget);
<a name="line53"></a>
<a name="line54"></a>
<a name="line55"></a>/**
<a name="line56"></a> * Generator for unique IDs.
<a name="line57"></a> * @type {goog.ui.IdGenerator}
<a name="line58"></a> * @private
<a name="line59"></a> */
<a name="line60"></a>goog.ui.Component.prototype.idGenerator_ = goog.ui.IdGenerator.getInstance();
<a name="line61"></a>
<a name="line62"></a>
<a name="line63"></a>/**
<a name="line64"></a> * The default right to left value.
<a name="line65"></a> * @type {boolean?}
<a name="line66"></a> * @private
<a name="line67"></a> */
<a name="line68"></a>goog.ui.Component.defaultRightToLeft_ = null;
<a name="line69"></a>
<a name="line70"></a>
<a name="line71"></a>/**
<a name="line72"></a> * Common events fired by components so that event propagation is useful.  Not
<a name="line73"></a> * all components are expected to dispatch or listen for all event types.
<a name="line74"></a> * Events dispatched before a state transition should be cancelable to prevent
<a name="line75"></a> * the corresponding state change.
<a name="line76"></a> * @enum {string}
<a name="line77"></a> */
<a name="line78"></a>goog.ui.Component.EventType = {
<a name="line79"></a>  /** Dispatched before the component becomes visible. */
<a name="line80"></a>  BEFORE_SHOW: &#39;beforeshow&#39;,
<a name="line81"></a>
<a name="line82"></a>  /**
<a name="line83"></a>   * Dispatched after the component becomes visible.
<a name="line84"></a>   * NOTE: For goog.ui.Container, this actually fires before containers
<a name="line85"></a>   * are shown.  Use goog.ui.Container.EventType.AFTER_SHOW if you want an event
<a name="line86"></a>   * that fires after a goog.ui.Container is shown.
<a name="line87"></a>   */
<a name="line88"></a>  SHOW: &#39;show&#39;,
<a name="line89"></a>
<a name="line90"></a>  /** Dispatched before the component becomes hidden. */
<a name="line91"></a>  HIDE: &#39;hide&#39;,
<a name="line92"></a>
<a name="line93"></a>  /** Dispatched before the component becomes disabled. */
<a name="line94"></a>  DISABLE: &#39;disable&#39;,
<a name="line95"></a>
<a name="line96"></a>  /** Dispatched before the component becomes enabled. */
<a name="line97"></a>  ENABLE: &#39;enable&#39;,
<a name="line98"></a>
<a name="line99"></a>  /** Dispatched before the component becomes highlighted. */
<a name="line100"></a>  HIGHLIGHT: &#39;highlight&#39;,
<a name="line101"></a>
<a name="line102"></a>  /** Dispatched before the component becomes un-highlighted. */
<a name="line103"></a>  UNHIGHLIGHT: &#39;unhighlight&#39;,
<a name="line104"></a>
<a name="line105"></a>  /** Dispatched before the component becomes activated. */
<a name="line106"></a>  ACTIVATE: &#39;activate&#39;,
<a name="line107"></a>
<a name="line108"></a>  /** Dispatched before the component becomes deactivated. */
<a name="line109"></a>  DEACTIVATE: &#39;deactivate&#39;,
<a name="line110"></a>
<a name="line111"></a>  /** Dispatched before the component becomes selected. */
<a name="line112"></a>  SELECT: &#39;select&#39;,
<a name="line113"></a>
<a name="line114"></a>  /** Dispatched before the component becomes un-selected. */
<a name="line115"></a>  UNSELECT: &#39;unselect&#39;,
<a name="line116"></a>
<a name="line117"></a>  /** Dispatched before a component becomes checked. */
<a name="line118"></a>  CHECK: &#39;check&#39;,
<a name="line119"></a>
<a name="line120"></a>  /** Dispatched before a component becomes un-checked. */
<a name="line121"></a>  UNCHECK: &#39;uncheck&#39;,
<a name="line122"></a>
<a name="line123"></a>  /** Dispatched before a component becomes focused. */
<a name="line124"></a>  FOCUS: &#39;focus&#39;,
<a name="line125"></a>
<a name="line126"></a>  /** Dispatched before a component becomes blurred. */
<a name="line127"></a>  BLUR: &#39;blur&#39;,
<a name="line128"></a>
<a name="line129"></a>  /** Dispatched before a component is opened (expanded). */
<a name="line130"></a>  OPEN: &#39;open&#39;,
<a name="line131"></a>
<a name="line132"></a>  /** Dispatched before a component is closed (collapsed). */
<a name="line133"></a>  CLOSE: &#39;close&#39;,
<a name="line134"></a>
<a name="line135"></a>  /** Dispatched after a component is moused over. */
<a name="line136"></a>  ENTER: &#39;enter&#39;,
<a name="line137"></a>
<a name="line138"></a>  /** Dispatched after a component is moused out of. */
<a name="line139"></a>  LEAVE: &#39;leave&#39;,
<a name="line140"></a>
<a name="line141"></a>  /** Dispatched after the user activates the component. */
<a name="line142"></a>  ACTION: &#39;action&#39;,
<a name="line143"></a>
<a name="line144"></a>  /** Dispatched after the external-facing state of a component is changed. */
<a name="line145"></a>  CHANGE: &#39;change&#39;
<a name="line146"></a>};
<a name="line147"></a>
<a name="line148"></a>
<a name="line149"></a>/**
<a name="line150"></a> * Errors thrown by the component.
<a name="line151"></a> * @enum {string}
<a name="line152"></a> */
<a name="line153"></a>goog.ui.Component.Error = {
<a name="line154"></a>  /**
<a name="line155"></a>   * Error when a method is not supported.
<a name="line156"></a>   */
<a name="line157"></a>  NOT_SUPPORTED: &#39;Method not supported&#39;,
<a name="line158"></a>
<a name="line159"></a>  /**
<a name="line160"></a>   * Error when the given element can not be decorated.
<a name="line161"></a>   */
<a name="line162"></a>  DECORATE_INVALID: &#39;Invalid element to decorate&#39;,
<a name="line163"></a>
<a name="line164"></a>  /**
<a name="line165"></a>   * Error when the component is already rendered and another render attempt is
<a name="line166"></a>   * made.
<a name="line167"></a>   */
<a name="line168"></a>  ALREADY_RENDERED: &#39;Component already rendered&#39;,
<a name="line169"></a>
<a name="line170"></a>  /**
<a name="line171"></a>   * Error when an attempt is made to set the parent of a component in a way
<a name="line172"></a>   * that would result in an inconsistent object graph.
<a name="line173"></a>   */
<a name="line174"></a>  PARENT_UNABLE_TO_BE_SET: &#39;Unable to set parent component&#39;,
<a name="line175"></a>
<a name="line176"></a>  /**
<a name="line177"></a>   * Error when an attempt is made to add a child component at an out-of-bounds
<a name="line178"></a>   * index.  We don&#39;t support sparse child arrays.
<a name="line179"></a>   */
<a name="line180"></a>  CHILD_INDEX_OUT_OF_BOUNDS: &#39;Child component index out of bounds&#39;,
<a name="line181"></a>
<a name="line182"></a>  /**
<a name="line183"></a>   * Error when an attempt is made to remove a child component from a component
<a name="line184"></a>   * other than its parent.
<a name="line185"></a>   */
<a name="line186"></a>  NOT_OUR_CHILD: &#39;Child is not in parent component&#39;,
<a name="line187"></a>
<a name="line188"></a>  /**
<a name="line189"></a>   * Error when an operation requiring DOM interaction is made when the
<a name="line190"></a>   * component is not in the document
<a name="line191"></a>   */
<a name="line192"></a>  NOT_IN_DOCUMENT: &#39;Operation not supported while component is not in document&#39;,
<a name="line193"></a>
<a name="line194"></a>  /**
<a name="line195"></a>   * Error when an invalid component state is encountered.
<a name="line196"></a>   */
<a name="line197"></a>  STATE_INVALID: &#39;Invalid component state&#39;
<a name="line198"></a>};
<a name="line199"></a>
<a name="line200"></a>
<a name="line201"></a>/**
<a name="line202"></a> * Common component states.  Components may have distinct appearance depending
<a name="line203"></a> * on what state(s) apply to them.  Not all components are expected to support
<a name="line204"></a> * all states.
<a name="line205"></a> * @enum {number}
<a name="line206"></a> */
<a name="line207"></a>goog.ui.Component.State = {
<a name="line208"></a>  /**
<a name="line209"></a>   * Union of all supported component states.
<a name="line210"></a>   */
<a name="line211"></a>  ALL: 0xFF,
<a name="line212"></a>
<a name="line213"></a>  /**
<a name="line214"></a>   * Component is disabled.
<a name="line215"></a>   * @see goog.ui.Component.EventType.DISABLE
<a name="line216"></a>   * @see goog.ui.Component.EventType.ENABLE
<a name="line217"></a>   */
<a name="line218"></a>  DISABLED: 0x01,
<a name="line219"></a>
<a name="line220"></a>  /**
<a name="line221"></a>   * Component is highlighted.
<a name="line222"></a>   * @see goog.ui.Component.EventType.HIGHLIGHT
<a name="line223"></a>   * @see goog.ui.Component.EventType.UNHIGHLIGHT
<a name="line224"></a>   */
<a name="line225"></a>  HOVER: 0x02,
<a name="line226"></a>
<a name="line227"></a>  /**
<a name="line228"></a>   * Component is active (or &quot;pressed&quot;).
<a name="line229"></a>   * @see goog.ui.Component.EventType.ACTIVATE
<a name="line230"></a>   * @see goog.ui.Component.EventType.DEACTIVATE
<a name="line231"></a>   */
<a name="line232"></a>  ACTIVE: 0x04,
<a name="line233"></a>
<a name="line234"></a>  /**
<a name="line235"></a>   * Component is selected.
<a name="line236"></a>   * @see goog.ui.Component.EventType.SELECT
<a name="line237"></a>   * @see goog.ui.Component.EventType.UNSELECT
<a name="line238"></a>   */
<a name="line239"></a>  SELECTED: 0x08,
<a name="line240"></a>
<a name="line241"></a>  /**
<a name="line242"></a>   * Component is checked.
<a name="line243"></a>   * @see goog.ui.Component.EventType.CHECK
<a name="line244"></a>   * @see goog.ui.Component.EventType.UNCHECK
<a name="line245"></a>   */
<a name="line246"></a>  CHECKED: 0x10,
<a name="line247"></a>
<a name="line248"></a>  /**
<a name="line249"></a>   * Component has focus.
<a name="line250"></a>   * @see goog.ui.Component.EventType.FOCUS
<a name="line251"></a>   * @see goog.ui.Component.EventType.BLUR
<a name="line252"></a>   */
<a name="line253"></a>  FOCUSED: 0x20,
<a name="line254"></a>
<a name="line255"></a>  /**
<a name="line256"></a>   * Component is opened (expanded).  Applies to tree nodes, menu buttons,
<a name="line257"></a>   * submenus, zippys (zippies?), etc.
<a name="line258"></a>   * @see goog.ui.Component.EventType.OPEN
<a name="line259"></a>   * @see goog.ui.Component.EventType.CLOSE
<a name="line260"></a>   */
<a name="line261"></a>  OPENED: 0x40
<a name="line262"></a>};
<a name="line263"></a>
<a name="line264"></a>
<a name="line265"></a>/**
<a name="line266"></a> * Static helper method; returns the type of event components are expected to
<a name="line267"></a> * dispatch when transitioning to or from the given state.
<a name="line268"></a> * @param {goog.ui.Component.State} state State to/from which the component
<a name="line269"></a> *     is transitioning.
<a name="line270"></a> * @param {boolean} isEntering Whether the component is entering or leaving the
<a name="line271"></a> *     state.
<a name="line272"></a> * @return {goog.ui.Component.EventType} Event type to dispatch.
<a name="line273"></a> */
<a name="line274"></a>goog.ui.Component.getStateTransitionEvent = function(state, isEntering) {
<a name="line275"></a>  switch (state) {
<a name="line276"></a>    case goog.ui.Component.State.DISABLED:
<a name="line277"></a>      return isEntering ? goog.ui.Component.EventType.DISABLE :
<a name="line278"></a>          goog.ui.Component.EventType.ENABLE;
<a name="line279"></a>    case goog.ui.Component.State.HOVER:
<a name="line280"></a>      return isEntering ? goog.ui.Component.EventType.HIGHLIGHT :
<a name="line281"></a>          goog.ui.Component.EventType.UNHIGHLIGHT;
<a name="line282"></a>    case goog.ui.Component.State.ACTIVE:
<a name="line283"></a>      return isEntering ? goog.ui.Component.EventType.ACTIVATE :
<a name="line284"></a>          goog.ui.Component.EventType.DEACTIVATE;
<a name="line285"></a>    case goog.ui.Component.State.SELECTED:
<a name="line286"></a>      return isEntering ? goog.ui.Component.EventType.SELECT :
<a name="line287"></a>          goog.ui.Component.EventType.UNSELECT;
<a name="line288"></a>    case goog.ui.Component.State.CHECKED:
<a name="line289"></a>      return isEntering ? goog.ui.Component.EventType.CHECK :
<a name="line290"></a>          goog.ui.Component.EventType.UNCHECK;
<a name="line291"></a>    case goog.ui.Component.State.FOCUSED:
<a name="line292"></a>      return isEntering ? goog.ui.Component.EventType.FOCUS :
<a name="line293"></a>          goog.ui.Component.EventType.BLUR;
<a name="line294"></a>    case goog.ui.Component.State.OPENED:
<a name="line295"></a>      return isEntering ? goog.ui.Component.EventType.OPEN :
<a name="line296"></a>          goog.ui.Component.EventType.CLOSE;
<a name="line297"></a>    default:
<a name="line298"></a>      // Fall through.
<a name="line299"></a>  }
<a name="line300"></a>
<a name="line301"></a>  // Invalid state.
<a name="line302"></a>  throw Error(goog.ui.Component.Error.STATE_INVALID);
<a name="line303"></a>};
<a name="line304"></a>
<a name="line305"></a>
<a name="line306"></a>/**
<a name="line307"></a> * Set the default right-to-left value. This causes all component&#39;s created from
<a name="line308"></a> * this point foward to have the given value. This is useful for cases where
<a name="line309"></a> * a given page is always in one directionality, avoiding unnecessary
<a name="line310"></a> * right to left determinations.
<a name="line311"></a> * @param {boolean?} rightToLeft Whether the components should be rendered
<a name="line312"></a> *     right-to-left. Null iff components should determine their directionality.
<a name="line313"></a> */
<a name="line314"></a>goog.ui.Component.setDefaultRightToLeft = function(rightToLeft) {
<a name="line315"></a>  goog.ui.Component.defaultRightToLeft_ = rightToLeft;
<a name="line316"></a>};
<a name="line317"></a>
<a name="line318"></a>
<a name="line319"></a>/**
<a name="line320"></a> * Unique ID of the component, lazily initialized in {@link
<a name="line321"></a> * goog.ui.Component#getId} if needed.  This property is strictly private and
<a name="line322"></a> * must not be accessed directly outside of this class!
<a name="line323"></a> * @type {string?}
<a name="line324"></a> * @private
<a name="line325"></a> */
<a name="line326"></a>goog.ui.Component.prototype.id_ = null;
<a name="line327"></a>
<a name="line328"></a>
<a name="line329"></a>/**
<a name="line330"></a> * DomHelper used to interact with the document, allowing components to be
<a name="line331"></a> * created in a different window.
<a name="line332"></a> * @type {goog.dom.DomHelper?}
<a name="line333"></a> * @protected
<a name="line334"></a> * @suppress {underscore}
<a name="line335"></a> */
<a name="line336"></a>goog.ui.Component.prototype.dom_ = null;
<a name="line337"></a>
<a name="line338"></a>
<a name="line339"></a>/**
<a name="line340"></a> * Whether the component is in the document.
<a name="line341"></a> * @type {boolean}
<a name="line342"></a> * @private
<a name="line343"></a> */
<a name="line344"></a>goog.ui.Component.prototype.inDocument_ = false;
<a name="line345"></a>
<a name="line346"></a>
<a name="line347"></a>// TODO: Stop referring to this private field in subclasses.
<a name="line348"></a>/**
<a name="line349"></a> * The DOM element for the component.
<a name="line350"></a> * @type {Element?}
<a name="line351"></a> * @private
<a name="line352"></a> */
<a name="line353"></a>goog.ui.Component.prototype.element_ = null;
<a name="line354"></a>
<a name="line355"></a>
<a name="line356"></a>/**
<a name="line357"></a> * Event handler.
<a name="line358"></a> * TODO: rename it to handler_ after all component subclasses in
<a name="line359"></a> * inside Google have been cleaned up.
<a name="line360"></a> * Code search: http://go/component_code_search
<a name="line361"></a> * @type {goog.events.EventHandler}
<a name="line362"></a> * @private
<a name="line363"></a> */
<a name="line364"></a>goog.ui.Component.prototype.googUiComponentHandler_;
<a name="line365"></a>
<a name="line366"></a>
<a name="line367"></a>/**
<a name="line368"></a> * Whether the component is rendered right-to-left.  Right-to-left is set
<a name="line369"></a> * lazily when {@link #isRightToLeft} is called the first time, unless it has
<a name="line370"></a> * been set by calling {@link #setRightToLeft} explicitly.
<a name="line371"></a> * @type {boolean?}
<a name="line372"></a> * @private
<a name="line373"></a> */
<a name="line374"></a>goog.ui.Component.prototype.rightToLeft_ = null;
<a name="line375"></a>
<a name="line376"></a>
<a name="line377"></a>/**
<a name="line378"></a> * Arbitrary data object associated with the component.  Such as meta-data.
<a name="line379"></a> * @type {*}
<a name="line380"></a> * @private
<a name="line381"></a> */
<a name="line382"></a>goog.ui.Component.prototype.model_ = null;
<a name="line383"></a>
<a name="line384"></a>
<a name="line385"></a>/**
<a name="line386"></a> * Parent component to which events will be propagated.  This property is
<a name="line387"></a> * strictly private and must not be accessed directly outside of this class!
<a name="line388"></a> * @type {goog.ui.Component?}
<a name="line389"></a> * @private
<a name="line390"></a> */
<a name="line391"></a>goog.ui.Component.prototype.parent_ = null;
<a name="line392"></a>
<a name="line393"></a>
<a name="line394"></a>/**
<a name="line395"></a> * Array of child components.  Lazily initialized on first use.  Must be kept in
<a name="line396"></a> * sync with {@code childIndex_}.  This property is strictly private and must
<a name="line397"></a> * not be accessed directly outside of this class!
<a name="line398"></a> * @type {Array.&lt;goog.ui.Component&gt;?}
<a name="line399"></a> * @private
<a name="line400"></a> */
<a name="line401"></a>goog.ui.Component.prototype.children_ = null;
<a name="line402"></a>
<a name="line403"></a>
<a name="line404"></a>/**
<a name="line405"></a> * Map of child component IDs to child components.  Used for constant-time
<a name="line406"></a> * random access to child components by ID.  Lazily initialized on first use.
<a name="line407"></a> * Must be kept in sync with {@code children_}.  This property is strictly
<a name="line408"></a> * private and must not be accessed directly outside of this class!
<a name="line409"></a> *
<a name="line410"></a> * We use a plain Object, not a {@link goog.structs.Map}, for simplicity.
<a name="line411"></a> * This means components can&#39;t have children with IDs such as &#39;constructor&#39; or
<a name="line412"></a> * &#39;valueOf&#39;, but this shouldn&#39;t really be an issue in practice, and if it is,
<a name="line413"></a> * we can always fix it later without changing the API.
<a name="line414"></a> *
<a name="line415"></a> * @type {Object?}
<a name="line416"></a> * @private
<a name="line417"></a> */
<a name="line418"></a>goog.ui.Component.prototype.childIndex_ = null;
<a name="line419"></a>
<a name="line420"></a>
<a name="line421"></a>/**
<a name="line422"></a> * Flag used to keep track of whether a component decorated an already existing
<a name="line423"></a> * element or whether it created the DOM itself.  If an element was decorated
<a name="line424"></a> * dispose will remove the node from the document, it is left up to the app.
<a name="line425"></a> * @type {boolean}
<a name="line426"></a> * @private
<a name="line427"></a> */
<a name="line428"></a>goog.ui.Component.prototype.wasDecorated_ = false;
<a name="line429"></a>
<a name="line430"></a>
<a name="line431"></a>/**
<a name="line432"></a> * Gets the unique ID for the instance of this component.  If the instance
<a name="line433"></a> * doesn&#39;t already have an ID, generates one on the fly.
<a name="line434"></a> * @return {string} Unique component ID.
<a name="line435"></a> */
<a name="line436"></a>goog.ui.Component.prototype.getId = function() {
<a name="line437"></a>  return this.id_ || (this.id_ = this.idGenerator_.getNextUniqueId());
<a name="line438"></a>};
<a name="line439"></a>
<a name="line440"></a>
<a name="line441"></a>/**
<a name="line442"></a> * Assigns an ID to this component instance.  It is the caller&#39;s responsibility
<a name="line443"></a> * to guarantee that the ID is unique.  If the component is a child of a parent
<a name="line444"></a> * component, then the parent component&#39;s child index is updated to reflect the
<a name="line445"></a> * new ID; this may throw an error if the parent already has a child with an ID
<a name="line446"></a> * that conflicts with the new ID.
<a name="line447"></a> * @param {string} id Unique component ID.
<a name="line448"></a> */
<a name="line449"></a>goog.ui.Component.prototype.setId = function(id) {
<a name="line450"></a>  if (this.parent_ &amp;&amp; this.parent_.childIndex_) {
<a name="line451"></a>    // Update the parent&#39;s child index.
<a name="line452"></a>    goog.object.remove(this.parent_.childIndex_, this.id_);
<a name="line453"></a>    goog.object.add(this.parent_.childIndex_, id, this);
<a name="line454"></a>  }
<a name="line455"></a>
<a name="line456"></a>  // Update the component ID.
<a name="line457"></a>  this.id_ = id;
<a name="line458"></a>};
<a name="line459"></a>
<a name="line460"></a>
<a name="line461"></a>/**
<a name="line462"></a> * Gets the component&#39;s element.
<a name="line463"></a> * @return {Element?} The element for the component.
<a name="line464"></a> */
<a name="line465"></a>goog.ui.Component.prototype.getElement = function() {
<a name="line466"></a>  return this.element_;
<a name="line467"></a>};
<a name="line468"></a>
<a name="line469"></a>
<a name="line470"></a>/**
<a name="line471"></a> * Sets the component&#39;s root element to the given element.  Considered
<a name="line472"></a> * protected and final.
<a name="line473"></a> * @param {Element} element Root element for the component.
<a name="line474"></a> * @protected
<a name="line475"></a> */
<a name="line476"></a>goog.ui.Component.prototype.setElementInternal = function(element) {
<a name="line477"></a>  this.element_ = element;
<a name="line478"></a>};
<a name="line479"></a>
<a name="line480"></a>
<a name="line481"></a>/**
<a name="line482"></a> * Returns the event handler for this component, lazily created the first time
<a name="line483"></a> * this method is called.
<a name="line484"></a> * @return {!goog.events.EventHandler} Event handler for this component.
<a name="line485"></a> * @protected
<a name="line486"></a> */
<a name="line487"></a>goog.ui.Component.prototype.getHandler = function() {
<a name="line488"></a>  return this.googUiComponentHandler_ ||
<a name="line489"></a>         (this.googUiComponentHandler_ = new goog.events.EventHandler(this));
<a name="line490"></a>};
<a name="line491"></a>
<a name="line492"></a>
<a name="line493"></a>/**
<a name="line494"></a> * Sets the parent of this component to use for event bubbling.  Throws an error
<a name="line495"></a> * if the component already has a parent or if an attempt is made to add a
<a name="line496"></a> * component to itself as a child.  Callers must use {@code removeChild}
<a name="line497"></a> * or {@code removeChildAt} to remove components from their containers before
<a name="line498"></a> * calling this method.
<a name="line499"></a> * @see goog.ui.Component#removeChild
<a name="line500"></a> * @see goog.ui.Component#removeChildAt
<a name="line501"></a> * @param {goog.ui.Component} parent The parent component.
<a name="line502"></a> */
<a name="line503"></a>goog.ui.Component.prototype.setParent = function(parent) {
<a name="line504"></a>  if (this == parent) {
<a name="line505"></a>    // Attempting to add a child to itself is an error.
<a name="line506"></a>    throw Error(goog.ui.Component.Error.PARENT_UNABLE_TO_BE_SET);
<a name="line507"></a>  }
<a name="line508"></a>
<a name="line509"></a>  if (parent &amp;&amp; this.parent_ &amp;&amp; this.id_ &amp;&amp; this.parent_.getChild(this.id_) &amp;&amp;
<a name="line510"></a>      this.parent_ != parent) {
<a name="line511"></a>    // This component is already the child of some parent, so it should be
<a name="line512"></a>    // removed using removeChild/removeChildAt first.
<a name="line513"></a>    throw Error(goog.ui.Component.Error.PARENT_UNABLE_TO_BE_SET);
<a name="line514"></a>  }
<a name="line515"></a>
<a name="line516"></a>  this.parent_ = parent;
<a name="line517"></a>  goog.ui.Component.superClass_.setParentEventTarget.call(this, parent);
<a name="line518"></a>};
<a name="line519"></a>
<a name="line520"></a>
<a name="line521"></a>/**
<a name="line522"></a> * Returns the component&#39;s parent, if any.
<a name="line523"></a> * @return {goog.ui.Component?} The parent component.
<a name="line524"></a> */
<a name="line525"></a>goog.ui.Component.prototype.getParent = function() {
<a name="line526"></a>  return this.parent_;
<a name="line527"></a>};
<a name="line528"></a>
<a name="line529"></a>
<a name="line530"></a>/**
<a name="line531"></a> * Overrides {@link goog.events.EventTarget#setParentEventTarget} to throw an
<a name="line532"></a> * error if the parent component is set, and the argument is not the parent.
<a name="line533"></a> *
<a name="line534"></a> * @param {goog.events.EventTarget} parent Parent EventTarget (null if none).
<a name="line535"></a> */
<a name="line536"></a>goog.ui.Component.prototype.setParentEventTarget = function(parent) {
<a name="line537"></a>  if (this.parent_ &amp;&amp; this.parent_ != parent) {
<a name="line538"></a>    throw Error(goog.ui.Component.Error.NOT_SUPPORTED);
<a name="line539"></a>  }
<a name="line540"></a>  goog.ui.Component.superClass_.setParentEventTarget.call(this, parent);
<a name="line541"></a>};
<a name="line542"></a>
<a name="line543"></a>
<a name="line544"></a>/**
<a name="line545"></a> * Returns the dom helper that is being used on this component.
<a name="line546"></a> * @return {goog.dom.DomHelper} The dom helper used on this component.
<a name="line547"></a> */
<a name="line548"></a>goog.ui.Component.prototype.getDomHelper = function() {
<a name="line549"></a>  return this.dom_;
<a name="line550"></a>};
<a name="line551"></a>
<a name="line552"></a>
<a name="line553"></a>/**
<a name="line554"></a> * Determines whether the component has been added to the document.
<a name="line555"></a> * @return {boolean} TRUE if rendered. Otherwise, FALSE.
<a name="line556"></a> */
<a name="line557"></a>goog.ui.Component.prototype.isInDocument = function() {
<a name="line558"></a>  return this.inDocument_;
<a name="line559"></a>};
<a name="line560"></a>
<a name="line561"></a>
<a name="line562"></a>/**
<a name="line563"></a> * Creates the initial DOM representation for the component.  The default
<a name="line564"></a> * implementation is to set this.element_ = div.
<a name="line565"></a> */
<a name="line566"></a>goog.ui.Component.prototype.createDom = function() {
<a name="line567"></a>  this.element_ = this.dom_.createElement(&#39;div&#39;);
<a name="line568"></a>};
<a name="line569"></a>
<a name="line570"></a>
<a name="line571"></a>/**
<a name="line572"></a> * Renders the component.  If a parent element is supplied, it should already be
<a name="line573"></a> * in the document and then the component&#39;s element will be appended to it.  If
<a name="line574"></a> * there is no optional parent element and the element doesn&#39;t have a parentNode
<a name="line575"></a> * then it will be appended to the document body.
<a name="line576"></a> *
<a name="line577"></a> * Throws an Error if the component is already rendered.
<a name="line578"></a> *
<a name="line579"></a> * @param {Element} opt_parentElement Optional parent element to render the
<a name="line580"></a> *    component into.
<a name="line581"></a> */
<a name="line582"></a>goog.ui.Component.prototype.render = function(opt_parentElement) {
<a name="line583"></a>  this.render_(opt_parentElement);
<a name="line584"></a>};
<a name="line585"></a>
<a name="line586"></a>
<a name="line587"></a>/**
<a name="line588"></a> * Renders the component before another element. The other element should be in
<a name="line589"></a> * the document already.
<a name="line590"></a> *
<a name="line591"></a> * Throws an Error if the component is already rendered.
<a name="line592"></a> *
<a name="line593"></a> * @param {Element} siblingElement  Element to render the component before.
<a name="line594"></a> */
<a name="line595"></a>goog.ui.Component.prototype.renderBefore = function(siblingElement) {
<a name="line596"></a>  this.render_(/** @type {Element} */(siblingElement.parentNode),
<a name="line597"></a>               siblingElement);
<a name="line598"></a>};
<a name="line599"></a>
<a name="line600"></a>
<a name="line601"></a>/**
<a name="line602"></a> * Renders the component.  If a parent element is supplied, it should already be
<a name="line603"></a> * in the document and then the component&#39;s element will be appended to it.  If
<a name="line604"></a> * there is no optional parent element and the element doesn&#39;t have a parentNode
<a name="line605"></a> * then it will be appended to the document body.
<a name="line606"></a> *
<a name="line607"></a> * Throws an Error if the component is already rendered.
<a name="line608"></a> *
<a name="line609"></a> * @param {Element} opt_parentElement Optional parent element to render the
<a name="line610"></a> *    component into.
<a name="line611"></a> * @param {Element} opt_beforeElement Element before which the component is to
<a name="line612"></a> *    be rendered.  If left out the node is appended to the parent element.
<a name="line613"></a> * @private
<a name="line614"></a> */
<a name="line615"></a>goog.ui.Component.prototype.render_ = function(opt_parentElement,
<a name="line616"></a>                                               opt_beforeElement) {
<a name="line617"></a>  if (this.inDocument_) {
<a name="line618"></a>    throw Error(goog.ui.Component.Error.ALREADY_RENDERED);
<a name="line619"></a>  }
<a name="line620"></a>
<a name="line621"></a>  if (!this.element_) {
<a name="line622"></a>    this.createDom();
<a name="line623"></a>  }
<a name="line624"></a>
<a name="line625"></a>  if (opt_parentElement) {
<a name="line626"></a>    opt_parentElement.insertBefore(this.element_, opt_beforeElement || null);
<a name="line627"></a>  } else {
<a name="line628"></a>    this.dom_.getDocument().body.appendChild(this.element_);
<a name="line629"></a>  }
<a name="line630"></a>
<a name="line631"></a>  // If this component has a parent component that isn&#39;t in the document yet,
<a name="line632"></a>  // we don&#39;t call enterDocument() here.  Instead, when the parent component
<a name="line633"></a>  // enters the document, the enterDocument() call will propagate to its
<a name="line634"></a>  // children, including this one.  If the component doesn&#39;t have a parent
<a name="line635"></a>  // or if the parent is already in the document, we call enterDocument().
<a name="line636"></a>  if (!this.parent_ || this.parent_.isInDocument()) {
<a name="line637"></a>    this.enterDocument();
<a name="line638"></a>  }
<a name="line639"></a>};
<a name="line640"></a>
<a name="line641"></a>
<a name="line642"></a>/**
<a name="line643"></a> * Decorates the element for the UI component.
<a name="line644"></a> * @param {Element} element Element to decorate.
<a name="line645"></a> */
<a name="line646"></a>goog.ui.Component.prototype.decorate = function(element) {
<a name="line647"></a>  if (this.inDocument_) {
<a name="line648"></a>    throw Error(goog.ui.Component.Error.ALREADY_RENDERED);
<a name="line649"></a>  } else if (element &amp;&amp; this.canDecorate(element)) {
<a name="line650"></a>    this.wasDecorated_ = true;
<a name="line651"></a>
<a name="line652"></a>    // Set the DOM helper of the component to match the decorated element.
<a name="line653"></a>    if (!this.dom_ ||
<a name="line654"></a>        this.dom_.getDocument() != goog.dom.getOwnerDocument(element)) {
<a name="line655"></a>      this.dom_ = goog.dom.getDomHelper(element);
<a name="line656"></a>    }
<a name="line657"></a>
<a name="line658"></a>    // Call specific component decorate logic.
<a name="line659"></a>    this.decorateInternal(element);
<a name="line660"></a>    this.enterDocument();
<a name="line661"></a>  } else {
<a name="line662"></a>    throw Error(goog.ui.Component.Error.DECORATE_INVALID);
<a name="line663"></a>  }
<a name="line664"></a>};
<a name="line665"></a>
<a name="line666"></a>
<a name="line667"></a>/**
<a name="line668"></a> * Determines if a given element can be decorated by this type of component.
<a name="line669"></a> * This method should be overridden by inheriting objects.
<a name="line670"></a> * @param {Element} element Element to decorate.
<a name="line671"></a> * @return {boolean} True if the element can be decorated, false otherwise.
<a name="line672"></a> */
<a name="line673"></a>goog.ui.Component.prototype.canDecorate = function(element) {
<a name="line674"></a>  return true;
<a name="line675"></a>};
<a name="line676"></a>
<a name="line677"></a>
<a name="line678"></a>/**
<a name="line679"></a> * @return {boolean} Whether the component was decorated.
<a name="line680"></a> */
<a name="line681"></a>goog.ui.Component.prototype.wasDecorated = function() {
<a name="line682"></a>  return this.wasDecorated_;
<a name="line683"></a>};
<a name="line684"></a>
<a name="line685"></a>
<a name="line686"></a>/**
<a name="line687"></a> * Actually decorates the element. Should be overridden by inheriting objects.
<a name="line688"></a> * This method can assume there are checks to ensure the component has not
<a name="line689"></a> * already been rendered have occurred and that enter document will be called
<a name="line690"></a> * afterwards. This method is considered protected.
<a name="line691"></a> * @param {Element} element Element to decorate.
<a name="line692"></a> * @protected
<a name="line693"></a> */
<a name="line694"></a>goog.ui.Component.prototype.decorateInternal = function(element) {
<a name="line695"></a>  this.element_ = element;
<a name="line696"></a>};
<a name="line697"></a>
<a name="line698"></a>
<a name="line699"></a>/**
<a name="line700"></a> * Called when the component&#39;s element is known to be in the document. Anything
<a name="line701"></a> * using document.getElementById etc. should be done at this stage.
<a name="line702"></a> *
<a name="line703"></a> * If the component contains child components, this call is propagated to its
<a name="line704"></a> * children.
<a name="line705"></a> */
<a name="line706"></a>goog.ui.Component.prototype.enterDocument = function() {
<a name="line707"></a>  this.inDocument_ = true;
<a name="line708"></a>
<a name="line709"></a>  // Propagate enterDocument to child components that have a DOM, if any.
<a name="line710"></a>  this.forEachChild(function(child) {
<a name="line711"></a>    if (!child.isInDocument() &amp;&amp; child.getElement()) {
<a name="line712"></a>      child.enterDocument();
<a name="line713"></a>    }
<a name="line714"></a>  });
<a name="line715"></a>};
<a name="line716"></a>
<a name="line717"></a>
<a name="line718"></a>/**
<a name="line719"></a> * Called by dispose to clean up the elements and listeners created by a
<a name="line720"></a> * component, or by a parent component/application who has removed the
<a name="line721"></a> * component from the document but wants to reuse it later.
<a name="line722"></a> *
<a name="line723"></a> * If the component contains child components, this call is propagated to its
<a name="line724"></a> * children.
<a name="line725"></a> *
<a name="line726"></a> * It should be possible for the component to be rendered again once this method
<a name="line727"></a> * has been called.
<a name="line728"></a> */
<a name="line729"></a>goog.ui.Component.prototype.exitDocument = function() {
<a name="line730"></a>  // Propagate exitDocument to child components that have been rendered, if any.
<a name="line731"></a>  this.forEachChild(function(child) {
<a name="line732"></a>    if (child.isInDocument()) {
<a name="line733"></a>      child.exitDocument();
<a name="line734"></a>    }
<a name="line735"></a>  });
<a name="line736"></a>
<a name="line737"></a>  if (this.googUiComponentHandler_) {
<a name="line738"></a>    this.googUiComponentHandler_.removeAll();
<a name="line739"></a>  }
<a name="line740"></a>
<a name="line741"></a>  this.inDocument_ = false;
<a name="line742"></a>};
<a name="line743"></a>
<a name="line744"></a>
<a name="line745"></a>/**
<a name="line746"></a> * Disposes of the component.  Calls {@code exitDocument}, which is expected to
<a name="line747"></a> * remove event handlers and clean up the component.  Propagates the call to
<a name="line748"></a> * the component&#39;s children, if any. Removes the component&#39;s DOM from the
<a name="line749"></a> * document unless it was decorated.
<a name="line750"></a> * @override
<a name="line751"></a> */
<a name="line752"></a>goog.ui.Component.prototype.disposeInternal = function() {
<a name="line753"></a>  goog.ui.Component.superClass_.disposeInternal.call(this);
<a name="line754"></a>
<a name="line755"></a>  if (this.inDocument_) {
<a name="line756"></a>    this.exitDocument();
<a name="line757"></a>  }
<a name="line758"></a>
<a name="line759"></a>  if (this.googUiComponentHandler_) {
<a name="line760"></a>    this.googUiComponentHandler_.dispose();
<a name="line761"></a>    delete this.googUiComponentHandler_;
<a name="line762"></a>  }
<a name="line763"></a>
<a name="line764"></a>  // Disposes of the component&#39;s children, if any.
<a name="line765"></a>  this.forEachChild(function(child) {
<a name="line766"></a>    child.dispose();
<a name="line767"></a>  });
<a name="line768"></a>
<a name="line769"></a>  // Detach the component&#39;s element from the DOM, unless it was decorated.
<a name="line770"></a>  if (!this.wasDecorated_ &amp;&amp; this.element_) {
<a name="line771"></a>    goog.dom.removeNode(this.element_);
<a name="line772"></a>  }
<a name="line773"></a>
<a name="line774"></a>  this.children_ = null;
<a name="line775"></a>  this.childIndex_ = null;
<a name="line776"></a>  this.element_ = null;
<a name="line777"></a>  this.model_ = null;
<a name="line778"></a>  this.parent_ = null;
<a name="line779"></a>};
<a name="line780"></a>
<a name="line781"></a>
<a name="line782"></a>/**
<a name="line783"></a> * Helper function for subclasses that gets a unique id for a given fragment,
<a name="line784"></a> * this can be used by components to
<a name="line785"></a> * generate unique string ids for DOM elements
<a name="line786"></a> * @param {string} idFragment A partial id.
<a name="line787"></a> * @return {string} Unique element id.
<a name="line788"></a> */
<a name="line789"></a>goog.ui.Component.prototype.makeId = function(idFragment) {
<a name="line790"></a>  return this.getId() + &#39;.&#39; + idFragment;
<a name="line791"></a>};
<a name="line792"></a>
<a name="line793"></a>
<a name="line794"></a>/**
<a name="line795"></a> * Returns the model associated with the UI component.
<a name="line796"></a> * @return {*} The model.
<a name="line797"></a> */
<a name="line798"></a>goog.ui.Component.prototype.getModel = function() {
<a name="line799"></a>  return this.model_;
<a name="line800"></a>};
<a name="line801"></a>
<a name="line802"></a>
<a name="line803"></a>/**
<a name="line804"></a> * Sets the model associated with the UI component.
<a name="line805"></a> * @param {*} obj The model.
<a name="line806"></a> */
<a name="line807"></a>goog.ui.Component.prototype.setModel = function(obj) {
<a name="line808"></a>  this.model_ = obj;
<a name="line809"></a>};
<a name="line810"></a>
<a name="line811"></a>
<a name="line812"></a>/**
<a name="line813"></a> * Helper function for returning the fragment portion of an id generated using
<a name="line814"></a> * makeId().
<a name="line815"></a> * @param {string} id Id generated with makeId().
<a name="line816"></a> * @return {string} Fragment.
<a name="line817"></a> */
<a name="line818"></a>goog.ui.Component.prototype.getFragmentFromId = function(id) {
<a name="line819"></a>  return id.substring(this.getId().length + 1);
<a name="line820"></a>};
<a name="line821"></a>
<a name="line822"></a>
<a name="line823"></a>/**
<a name="line824"></a> * Helper function for returning an element in the document with a unique id
<a name="line825"></a> * generated using makeId().
<a name="line826"></a> * @param {string} idFragment The partial id.
<a name="line827"></a> * @return {Element?} The element with the unique id, or null if it cannot be
<a name="line828"></a> *     found.
<a name="line829"></a> */
<a name="line830"></a>goog.ui.Component.prototype.getElementByFragment = function(idFragment) {
<a name="line831"></a>  if (!this.inDocument_) {
<a name="line832"></a>    throw Error(goog.ui.Component.Error.NOT_IN_DOCUMENT);
<a name="line833"></a>  }
<a name="line834"></a>  return this.dom_.getElement(this.makeId(idFragment));
<a name="line835"></a>};
<a name="line836"></a>
<a name="line837"></a>
<a name="line838"></a>/**
<a name="line839"></a> * Adds the specified component as the last child of this component.  See
<a name="line840"></a> * {@link goog.ui.Component#addChildAt} for detailed semantics.
<a name="line841"></a> *
<a name="line842"></a> * @see goog.ui.Component#addChildAt
<a name="line843"></a> * @param {goog.ui.Component} child The new child component.
<a name="line844"></a> * @param {boolean} opt_render If true, the child component will be rendered
<a name="line845"></a> *    into the parent.
<a name="line846"></a> */
<a name="line847"></a>goog.ui.Component.prototype.addChild = function(child, opt_render) {
<a name="line848"></a>  this.addChildAt(child, this.getChildCount(), opt_render);
<a name="line849"></a>};
<a name="line850"></a>
<a name="line851"></a>
<a name="line852"></a>/**
<a name="line853"></a> * Adds the specified component as a child of this component at the given
<a name="line854"></a> * 0-based index.
<a name="line855"></a> *
<a name="line856"></a> * Both {@code addChild} and {@code addChildAt} assume the following contract
<a name="line857"></a> * between parent and child components:
<a name="line858"></a> *  &lt;ul&gt;
<a name="line859"></a> *    &lt;li&gt;the child component&#39;s element must be a descendant of the parent
<a name="line860"></a> *        component&#39;s element, and
<a name="line861"></a> *    &lt;li&gt;the DOM state of the child component must be consistent with the DOM
<a name="line862"></a> *        state of the parent component (see {@code isInDocument}).
<a name="line863"></a> *  &lt;/ul&gt;
<a name="line864"></a> *
<a name="line865"></a> * In particular, {@code parent.addChild(child)} will throw an error if the
<a name="line866"></a> * child component is already in the document, but the parent isn&#39;t.
<a name="line867"></a> *
<a name="line868"></a> * Clients of this API may call {@code addChild} and {@code addChildAt} with
<a name="line869"></a> * {@code opt_render} set to true.  If {@code opt_render} is true, calling these
<a name="line870"></a> * methods will automatically render the child component&#39;s element into the
<a name="line871"></a> * parent component&#39;s element.  However, {@code parent.addChild(child, true)}
<a name="line872"></a> * will throw an error if:
<a name="line873"></a> *  &lt;ul&gt;
<a name="line874"></a> *    &lt;li&gt;the parent component has no DOM (i.e. {@code parent.getElement()} is
<a name="line875"></a> *        null), or
<a name="line876"></a> *    &lt;li&gt;the child component is already in the document, regardless of the
<a name="line877"></a> *        parent&#39;s DOM state.
<a name="line878"></a> *  &lt;/ul&gt;
<a name="line879"></a> *
<a name="line880"></a> * Finally, this method also throws an error if the new child already has a
<a name="line881"></a> * different parent, or the given index is out of bounds.
<a name="line882"></a> *
<a name="line883"></a> * @see goog.ui.Component#addChild
<a name="line884"></a> * @param {goog.ui.Component} child The new child component.
<a name="line885"></a> * @param {number} index 0-based index at which the new child component is to be
<a name="line886"></a> *    added; must be between 0 and the current child count (inclusive).
<a name="line887"></a> * @param {boolean} opt_render If true, the child component will be rendered
<a name="line888"></a> *    into the parent.
<a name="line889"></a> */
<a name="line890"></a>goog.ui.Component.prototype.addChildAt = function(child, index, opt_render) {
<a name="line891"></a>  if (child.inDocument_ &amp;&amp; (opt_render || !this.inDocument_)) {
<a name="line892"></a>    // Adding a child that&#39;s already in the document is an error, except if the
<a name="line893"></a>    // parent is also in the document and opt_render is false (e.g. decorate()).
<a name="line894"></a>    throw Error(goog.ui.Component.Error.ALREADY_RENDERED);
<a name="line895"></a>  }
<a name="line896"></a>
<a name="line897"></a>  if (index &lt; 0 || index &gt; this.getChildCount()) {
<a name="line898"></a>    // Allowing sparse child arrays would lead to strange behavior, so we don&#39;t.
<a name="line899"></a>    throw Error(goog.ui.Component.Error.CHILD_INDEX_OUT_OF_BOUNDS);
<a name="line900"></a>  }
<a name="line901"></a>
<a name="line902"></a>  // Create the index and the child array on first use.
<a name="line903"></a>  if (!this.childIndex_ || !this.children_) {
<a name="line904"></a>    this.childIndex_ = {};
<a name="line905"></a>    this.children_ = [];
<a name="line906"></a>  }
<a name="line907"></a>
<a name="line908"></a>  // Moving child within component, remove old reference.
<a name="line909"></a>  if (child.getParent() == this) {
<a name="line910"></a>    goog.object.set(this.childIndex_, child.getId(), child);
<a name="line911"></a>    goog.array.remove(this.children_, child);
<a name="line912"></a>
<a name="line913"></a>  // Add the child to this component.  goog.object.add() throws an error if
<a name="line914"></a>  // a child with the same ID already exists.
<a name="line915"></a>  } else {
<a name="line916"></a>    goog.object.add(this.childIndex_, child.getId(), child);
<a name="line917"></a>  }
<a name="line918"></a>
<a name="line919"></a>  // Set the parent of the child to this component.  This throws an error if
<a name="line920"></a>  // the child is already contained by another component.
<a name="line921"></a>  child.setParent(this);
<a name="line922"></a>  goog.array.insertAt(this.children_, child, index);
<a name="line923"></a>
<a name="line924"></a>  if (child.inDocument_ &amp;&amp; this.inDocument_ &amp;&amp; child.getParent() == this) {
<a name="line925"></a>    // Changing the position of an existing child, move the DOM node.
<a name="line926"></a>    var contentElement = this.getContentElement();
<a name="line927"></a>    contentElement.insertBefore(child.getElement(),
<a name="line928"></a>        (contentElement.childNodes[index + 1] || null));
<a name="line929"></a>
<a name="line930"></a>  } else if (opt_render) {
<a name="line931"></a>    // If this (parent) component doesn&#39;t have a DOM yet, call createDom now
<a name="line932"></a>    // to make sure we render the child component&#39;s element into the correct
<a name="line933"></a>    // parent element (otherwise render_ with a null first argument would
<a name="line934"></a>    // render the child into the document body, which is almost certainly not
<a name="line935"></a>    // what we want).
<a name="line936"></a>    if (!this.element_) {
<a name="line937"></a>      this.createDom();
<a name="line938"></a>    }
<a name="line939"></a>    // Render the child into the parent at the appropriate location.  Note that
<a name="line940"></a>    // getChildAt(index + 1) returns undefined if inserting at the end.
<a name="line941"></a>    // TODO: We should have a renderer with a renderChildAt API.
<a name="line942"></a>    var sibling = this.getChildAt(index + 1);
<a name="line943"></a>    // render_() calls enterDocument() if the parent is already in the document.
<a name="line944"></a>    child.render_(this.getContentElement(), sibling ? sibling.element_ : null);
<a name="line945"></a>  } else {
<a name="line946"></a>    // We don&#39;t touch the DOM, but if the parent is in the document, the child
<a name="line947"></a>    // isn&#39;t, and the child has a DOM, then we call enterDocument on the child.
<a name="line948"></a>    if (this.inDocument_ &amp;&amp; !child.inDocument_ &amp;&amp; child.element_) {
<a name="line949"></a>      child.enterDocument();
<a name="line950"></a>    }
<a name="line951"></a>  }
<a name="line952"></a>};
<a name="line953"></a>
<a name="line954"></a>
<a name="line955"></a>/**
<a name="line956"></a> * Returns the DOM element into which child components are to be rendered,
<a name="line957"></a> * or null if the component itself hasn&#39;t been rendered yet.  This default
<a name="line958"></a> * implementation returns the component&#39;s root element.  Subclasses with
<a name="line959"></a> * complex DOM structures must override this method.
<a name="line960"></a> * @return {Element?} Element to contain child elements (null if none).
<a name="line961"></a> */
<a name="line962"></a>goog.ui.Component.prototype.getContentElement = function() {
<a name="line963"></a>  return this.element_;
<a name="line964"></a>};
<a name="line965"></a>
<a name="line966"></a>
<a name="line967"></a>/**
<a name="line968"></a> * Returns true if the component is rendered right-to-left, false otherwise.
<a name="line969"></a> * The first time this function is invoked, the right-to-left rendering property
<a name="line970"></a> * is set if it has not been already.
<a name="line971"></a> * @return {boolean} Whether the control is rendered right-to-left.
<a name="line972"></a> */
<a name="line973"></a>goog.ui.Component.prototype.isRightToLeft = function() {
<a name="line974"></a>  if (this.rightToLeft_ == null) {
<a name="line975"></a>    this.rightToLeft_ = goog.style.isRightToLeft(this.inDocument_ ?
<a name="line976"></a>        this.element_ : this.dom_.getDocument().body);
<a name="line977"></a>  }
<a name="line978"></a>  return /** @type {boolean} */(this.rightToLeft_);
<a name="line979"></a>};
<a name="line980"></a>
<a name="line981"></a>
<a name="line982"></a>/**
<a name="line983"></a> * Set is right-to-left. This function should be used if the component needs
<a name="line984"></a> * to know the rendering direction during dom creation (i.e. before
<a name="line985"></a> * {@link #enterDocument} is called and is right-to-left is set).
<a name="line986"></a> * @param {boolean} rightToLeft Whether the component is rendered
<a name="line987"></a> *     right-to-left.
<a name="line988"></a> */
<a name="line989"></a>goog.ui.Component.prototype.setRightToLeft = function(rightToLeft) {
<a name="line990"></a>  if (this.inDocument_) {
<a name="line991"></a>    throw Error(goog.ui.Component.Error.ALREADY_RENDERED);
<a name="line992"></a>  }
<a name="line993"></a>  this.rightToLeft_ = rightToLeft;
<a name="line994"></a>};
<a name="line995"></a>
<a name="line996"></a>
<a name="line997"></a>/**
<a name="line998"></a> * Returns true if the component has children.
<a name="line999"></a> * @return {boolean} True if the component has children.
<a name="line1000"></a> */
<a name="line1001"></a>goog.ui.Component.prototype.hasChildren = function() {
<a name="line1002"></a>  return !!this.children_ &amp;&amp; this.children_.length != 0;
<a name="line1003"></a>};
<a name="line1004"></a>
<a name="line1005"></a>
<a name="line1006"></a>/**
<a name="line1007"></a> * Returns the number of children of this component.
<a name="line1008"></a> * @return {number} The number of children.
<a name="line1009"></a> */
<a name="line1010"></a>goog.ui.Component.prototype.getChildCount = function() {
<a name="line1011"></a>  return this.children_ ? this.children_.length : 0;
<a name="line1012"></a>};
<a name="line1013"></a>
<a name="line1014"></a>
<a name="line1015"></a>/**
<a name="line1016"></a> * Returns an array containing the IDs of the children of this component, or an
<a name="line1017"></a> * empty array if the component has no children.
<a name="line1018"></a> * @return {Array.&lt;string&gt;} Child component IDs.
<a name="line1019"></a> */
<a name="line1020"></a>goog.ui.Component.prototype.getChildIds = function() {
<a name="line1021"></a>  var ids = [];
<a name="line1022"></a>
<a name="line1023"></a>  // We don&#39;t use goog.object.getKeys(this.childIndex_) because we want to
<a name="line1024"></a>  // return the IDs in the correct order as determined by this.children_.
<a name="line1025"></a>  this.forEachChild(function(child) {
<a name="line1026"></a>    // addChild()/addChildAt() guarantee that the child array isn&#39;t sparse.
<a name="line1027"></a>    ids.push(child.getId());
<a name="line1028"></a>  });
<a name="line1029"></a>
<a name="line1030"></a>  return ids;
<a name="line1031"></a>};
<a name="line1032"></a>
<a name="line1033"></a>
<a name="line1034"></a>/**
<a name="line1035"></a> * Returns the child with the given ID, or null if no such child exists.
<a name="line1036"></a> * @param {string} id Child component ID.
<a name="line1037"></a> * @return {goog.ui.Component?} The child with the given ID; null if none.
<a name="line1038"></a> */
<a name="line1039"></a>goog.ui.Component.prototype.getChild = function(id) {
<a name="line1040"></a>  // Use childIndex_ for O(1) access by ID.
<a name="line1041"></a>  return (this.childIndex_ &amp;&amp; id) ? (/** @type {goog.ui.Component} */
<a name="line1042"></a>      goog.object.get(this.childIndex_, id)) || null : null;
<a name="line1043"></a>};
<a name="line1044"></a>
<a name="line1045"></a>
<a name="line1046"></a>/**
<a name="line1047"></a> * Returns the child at the given index, or null if the index is out of bounds.
<a name="line1048"></a> * @param {number} index 0-based index.
<a name="line1049"></a> * @return {goog.ui.Component?} The child at the given index; null if none.
<a name="line1050"></a> */
<a name="line1051"></a>goog.ui.Component.prototype.getChildAt = function(index) {
<a name="line1052"></a>  // Use children_ for access by index.
<a name="line1053"></a>  return this.children_ ? this.children_[index] || null : null;
<a name="line1054"></a>};
<a name="line1055"></a>
<a name="line1056"></a>
<a name="line1057"></a>/**
<a name="line1058"></a> * Calls the given function on each of this component&#39;s children in order.  If
<a name="line1059"></a> * {@code opt_obj} is provided, it will be used as the &#39;this&#39; object in the
<a name="line1060"></a> * function when called.  The function should take two arguments:  the child
<a name="line1061"></a> * component and its 0-based index.  The return value is ignored.
<a name="line1062"></a> * @param {Function} f The function to call for every child component; should
<a name="line1063"></a> *    take 2 arguments (the child and its index).
<a name="line1064"></a> * @param {Object} opt_obj Used as the &#39;this&#39; object in f when called.
<a name="line1065"></a> */
<a name="line1066"></a>goog.ui.Component.prototype.forEachChild = function(f, opt_obj) {
<a name="line1067"></a>  if (this.children_) {
<a name="line1068"></a>    goog.array.forEach(this.children_, f, opt_obj);
<a name="line1069"></a>  }
<a name="line1070"></a>};
<a name="line1071"></a>
<a name="line1072"></a>
<a name="line1073"></a>/**
<a name="line1074"></a> * Returns the 0-based index of the given child component, or -1 if no such
<a name="line1075"></a> * child is found.
<a name="line1076"></a> * @param {goog.ui.Component?} child The child component.
<a name="line1077"></a> * @return {number} 0-based index of the child component; -1 if not found.
<a name="line1078"></a> */
<a name="line1079"></a>goog.ui.Component.prototype.indexOfChild = function(child) {
<a name="line1080"></a>  return (this.children_ &amp;&amp; child) ? goog.array.indexOf(this.children_, child) :
<a name="line1081"></a>      -1;
<a name="line1082"></a>};
<a name="line1083"></a>
<a name="line1084"></a>
<a name="line1085"></a>/**
<a name="line1086"></a> * Removes the given child from this component, and returns it.  Throws an error
<a name="line1087"></a> * if the argument is invalid or if the specified child isn&#39;t found in the
<a name="line1088"></a> * parent component.  The argument can either be a string (interpreted as the
<a name="line1089"></a> * ID of the child component to remove) or the child component itself.
<a name="line1090"></a> *
<a name="line1091"></a> * If {@code opt_unrender} is true, calls {@link goog.ui.component#exitDocument}
<a name="line1092"></a> * on the removed child, and subsequently detaches the child&#39;s DOM from the
<a name="line1093"></a> * document.  Otherwise it is the caller&#39;s responsibility to clean up the child
<a name="line1094"></a> * component&#39;s DOM.
<a name="line1095"></a> *
<a name="line1096"></a> * @see goog.ui.Component#removeChildAt
<a name="line1097"></a> * @param {string|goog.ui.Component|null} child The ID of the child to remove,
<a name="line1098"></a> *    or the child component itself.
<a name="line1099"></a> * @param {boolean} opt_unrender If true, calls {@code exitDocument} on the
<a name="line1100"></a> *    removed child component, and detaches its DOM from the document.
<a name="line1101"></a> * @return {goog.ui.Component} The removed component, if any.
<a name="line1102"></a> */
<a name="line1103"></a>goog.ui.Component.prototype.removeChild = function(child, opt_unrender) {
<a name="line1104"></a>  if (child) {
<a name="line1105"></a>    // Normalize child to be the object and id to be the ID string.  This also
<a name="line1106"></a>    // ensures that the child is really ours.
<a name="line1107"></a>    var id = goog.isString(child) ? child : child.getId();
<a name="line1108"></a>    child = this.getChild(id);
<a name="line1109"></a>
<a name="line1110"></a>    if (id &amp;&amp; child) {
<a name="line1111"></a>      goog.object.remove(this.childIndex_, id);
<a name="line1112"></a>      goog.array.remove(this.children_, child);
<a name="line1113"></a>
<a name="line1114"></a>      if (opt_unrender) {
<a name="line1115"></a>        // Remove the child component&#39;s DOM from the document.  We have to call
<a name="line1116"></a>        // exitDocument first (see documentation).
<a name="line1117"></a>        child.exitDocument();
<a name="line1118"></a>        if (child.element_) {
<a name="line1119"></a>          goog.dom.removeNode(child.element_);
<a name="line1120"></a>        }
<a name="line1121"></a>      }
<a name="line1122"></a>
<a name="line1123"></a>      // Child&#39;s parent must be set to null after exitDocument is called
<a name="line1124"></a>      // so that the child can unlisten to its parent if required.
<a name="line1125"></a>      child.setParent(null);
<a name="line1126"></a>    }
<a name="line1127"></a>  }
<a name="line1128"></a>
<a name="line1129"></a>  if (!child) {
<a name="line1130"></a>    throw Error(goog.ui.Component.Error.NOT_OUR_CHILD);
<a name="line1131"></a>  }
<a name="line1132"></a>
<a name="line1133"></a>  return /** @type {goog.ui.Component} */(child);
<a name="line1134"></a>};
<a name="line1135"></a>
<a name="line1136"></a>
<a name="line1137"></a>/**
<a name="line1138"></a> * Removes the child at the given index from this component, and returns it.
<a name="line1139"></a> * Throws an error if the argument is out of bounds, or if the specified child
<a name="line1140"></a> * isn&#39;t found in the parent.  See {@link goog.ui.Component#removeChild} for
<a name="line1141"></a> * detailed semantics.
<a name="line1142"></a> *
<a name="line1143"></a> * @see goog.ui.Component#removeChild
<a name="line1144"></a> * @param {number} index 0-based index of the child to remove.
<a name="line1145"></a> * @param {boolean} opt_unrender If true, calls {@code exitDocument} on the
<a name="line1146"></a> *    removed child component, and detaches its DOM from the document.
<a name="line1147"></a> * @return {goog.ui.Component} The removed component, if any.
<a name="line1148"></a> */
<a name="line1149"></a>goog.ui.Component.prototype.removeChildAt = function(index, opt_unrender) {
<a name="line1150"></a>  // removeChild(null) will throw error.
<a name="line1151"></a>  return this.removeChild(this.getChildAt(index), opt_unrender);
<a name="line1152"></a>};
<a name="line1153"></a>
<a name="line1154"></a>
<a name="line1155"></a>/**
<a name="line1156"></a> * Removes every child component attached to this one.
<a name="line1157"></a> *
<a name="line1158"></a> * @see goog.ui.Component#removeChild
<a name="line1159"></a> * @param {boolean} opt_unrender If true, calls {@link #exitDocument} on the
<a name="line1160"></a> *    removed child components, and detaches their DOM from the document.
<a name="line1161"></a> */
<a name="line1162"></a>goog.ui.Component.prototype.removeChildren = function(opt_unrender) {
<a name="line1163"></a>  while (this.hasChildren()) {
<a name="line1164"></a>    this.removeChildAt(0, opt_unrender);
<a name="line1165"></a>  }
<a name="line1166"></a>};
</pre>


</body>
</html>
